<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="libman.css">
<TITLE>
Eplex Instances
</TITLE>
</HEAD>
<BODY >
<A HREF="libman053.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="libman055.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc106">9.2</A>&nbsp;&nbsp;Eplex Instances</H2><UL>
<LI><A HREF="libman054.html#toc54">Linear Constraints</A>
<LI><A HREF="libman054.html#toc55">Linear Expressions</A>
<LI><A HREF="libman054.html#toc56">Bounds</A>
<LI><A HREF="libman054.html#toc57">Integrality</A>
<LI><A HREF="libman054.html#toc58">Solving Simple Eplex Problems</A>
<LI><A HREF="libman054.html#toc59">Examples</A>
</UL>


In this chapter, the problem passed to the external solver will be referred
to as an <I>eplex problem</I>. An eplex problem consists of a set of linear
arithmetic constraints, whose variables have bounds and may possibly have
integrality constraints. The external solver will solve such a problem by optimising
these constraints with respect to an objective function. <BR>
<BR>
With the eplex library, it is possible to have more than one eplex problem
within one program. The simplest way to write such programs with the
library is through <I>Eplex Instances</I>. An eplex instance is an instance
of the eplex solver, to which an eplex problem can be sent. An external
<I>solver state</I> can be associated with each eplex instance, which can be
invoked to solve the eplex problem. Declaratively, an eplex instance can be
seen as a compound constraint consisting of all the variables, their bounds, and
constraints of the eplex problem.<BR>
<BR>
Like other solvers, each eplex instance has its own module. To use an eplex
instance, it must first be declared, so that the module can be created.
This is done by:<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/eplex_instance-1.html"><B>eplex_instance(+Name)</B></A><A NAME="@default280"></A></H4>
This predicate will initialise an eplex instance <TT>Name</TT>. Once
initialised, a <TT>Name</TT> module will exist, to which the user can post the 
constraints for the eplex problem and setup and use the external solver
state to solve the eplex problem. Normally, this predicate should be issued
as a directive in the user's program, so that the program code can refer to
the instance directly in their code. For example:
<PRE CLASS="verbatim">
   :- eplex_instance(instance).
</PRE>
For convenience, the eplex library declares <TT>eplex</TT> as an eplex instance 
when the library is loaded. <BR>
<BR>
<A NAME="toc54"></A>
<H3 CLASS="subsection"><A NAME="htoc107">9.2.1</A>&nbsp;&nbsp;Linear Constraints</H3>
<A NAME="linear-constraints"></A>
The constraints provided are equalities and inequalities over
linear expressions. 
Their operational behaviour is as follows:
<UL CLASS="itemize"><LI CLASS="li-itemize">
When they contain no variables, they simply succeed or fail.
<LI CLASS="li-itemize">When they contain exactly one variable, they are translated into
a bound update on that variable, which may in turn fail, succeed,
or even instantiate the variable.
Note that if the variable's type is integer, the bound will be adjusted
to the next suitable integral value.
<LI CLASS="li-itemize">Otherwise, the constraint is transferred to the external solver state
if the state has been setup. If it has not, the constraint
delays and is transferred to the external solver state when it is setup.
This mechanism makes it possible to interface to a non-incremental
black-box solver that requires all constraints at once,
or to send constraints to the solver in batches
</UL>
As with all predicates defined for an eplex instance, these constraints
should be module-qualified with the name of the eplex instance. In the 
following they are shown qualified with the <TT>eplex</TT> instance, and with 
brackets around the constraints when needed. Other instances can
be used if they have been declared using <B>eplex_instance/1</B>. <BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/SE-2.html"><B>EplexInstance: (X $= Y)</B></A><A NAME="@default281"></A></H4>
X is equal to Y. X and Y are linear expressions.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/SGE-2.html"><B>EplexInstance: (X $&gt;= Y)</B></A><A NAME="@default282"></A></H4>
X is greater or equal to Y. X and Y are linear expressions.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/SEL-2.html"><B>EplexInstance: (X $=&lt; Y)</B></A><A NAME="@default283"></A></H4>
X is less or equal to Y. X and Y are linear expressions.<BR>
<BR>
<A NAME="toc55"></A>
<H3 CLASS="subsection"><A NAME="htoc108">9.2.2</A>&nbsp;&nbsp;Linear Expressions</H3>
The following arithmetic expression can be used inside the constraints:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>X</B><DD CLASS="dd-description">
Variables. If X is not yet a problem variable, it is turned into one
	via an implicit declaration <TT>X $:: -1.0Inf..1.0Inf</TT>.<BR>
<BR>
<DT CLASS="dt-description"><B>123, 3.4</B><DD CLASS="dd-description">
Integer or floating point constants.<BR>
<BR>
<DT CLASS="dt-description"><B>+Expr</B><DD CLASS="dd-description">
Identity.<BR>
<BR>
<DT CLASS="dt-description"><B>-Expr</B><DD CLASS="dd-description">
Sign change.<BR>
<BR>
<DT CLASS="dt-description"><B>E1+E2</B><DD CLASS="dd-description">
Addition.<BR>
<BR>
<DT CLASS="dt-description"><B>sum(ListOfExpr)</B><DD CLASS="dd-description">
Equivalent to the sum of all list elements.<BR>
<BR>
<DT CLASS="dt-description"><B>E1-E2</B><DD CLASS="dd-description">
Subtraction.<BR>
<BR>
<DT CLASS="dt-description"><B>E1*E2</B><DD CLASS="dd-description">
Multiplication.<BR>
<BR>
<DT CLASS="dt-description"><B>ListOfExpr1*ListOfExpr2</B><DD CLASS="dd-description">
Scalar product: The sum of the products of the corresponding
elements in the two lists. The lists must be of equal length.
</DL>
<A NAME="toc56"></A>
<H3 CLASS="subsection"><A NAME="htoc109">9.2.3</A>&nbsp;&nbsp;Bounds</H3>
Bounds for variables can be given to an eplex instance via the <CODE>$::/2</CODE>
constraint:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <A HREF="../bips/lib/eplex/SNN-2.html"><B>EplexIntance: Vars $:: Lo..Hi</B></A><A NAME="@default284"></A><DD CLASS="dd-description">
 <A NAME="eplex-coloncolon2"></A>
 Restrict the external solver to assign solution values for the eplex
 problem within the bounds specified by Lo..Hi. 
 Passes to the external solver the bounds for the variables in Vars.
 Lo, Hi are the lower and upper bounds, respectively. Note that the
 bounds are only passed to the external solver if they would narrow the
 current bounds, and failure will occur if the resulting interval is empty. 
 Note also that the external solver does not do any bound propagation
 and will thus not change the bounds on its own. The default bounds for
 variables are notionally -1.0Inf..1.0Inf (where infinity is actually
 defined as the solver's notion of infinity).
</DL>
<A NAME="toc57"></A>
<H3 CLASS="subsection"><A NAME="htoc110">9.2.4</A>&nbsp;&nbsp;Integrality</H3>
The difference between using an LP vs. an MIP solver is made by
declaring integrality to the solver via the integers/1 constraint:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <A HREF="../bips/lib/eplex/integers-1.html"><B>EplexInstance:integers(Vars)</B></A><A NAME="@default285"></A><DD CLASS="dd-description">
 <A NAME="eplex-integers1"></A>
	Inform the external solver to treat the variables Vars as integral.
	It does not impose the integer type on Vars. However, when a 
 typed_solution is retrieved (via lp_get/3 or
 lp_var_get/3), this will be rounded to the nearest integer.<BR>
<BR>
Note that unless eplex:integers/1 (or lp_add/3, see
 section&nbsp;<A HREF="libman056.html#lp-add">9.4.2</A>) is invoked, any invocation
 of the eplex external solver (via lp_solve/2, lp_probe/3 or
	lp_demon_setup/5) will only solve a continuous relaxation, even
 when problem variables have been declared as integers in other
 solvers (e.g. ic).</DL>
Note that all the above constraints are local to the eplex instance; they
do not place any restrictions on the variables for other eplex instances or
solvers. Failure will occur only when inconsistency is detected within the
same eplex instance, unless the user explicitly try to merge the constraints
from different solvers/eplex instance.<BR>
<BR>
A counterpart, <A HREF="../bips/lib/eplex/reals-1.html"><B>reals/1</B></A><A NAME="@default286"></A> `constraint' also exists &ndash; this simply declares the
variables specified are problem variables, and does not actually place any
other constraint on the variables.<BR>
<BR>
<A NAME="toc58"></A>
<H3 CLASS="subsection"><A NAME="htoc111">9.2.5</A>&nbsp;&nbsp;Solving Simple Eplex Problems</H3>
<A NAME="solving-eplex"></A>
In order to solve an eplex problem, the eplex instance must be set up
for an external solver state. The solver state can then be invoked to
solve the problem. The simplest way to do this is to use:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <A HREF="../bips/lib/eplex/eplex_solver_setup-1.html"><B>EplexInstance:eplex_solver_setup(+Objective)</B></A><A NAME="@default287"></A><DD CLASS="dd-description">
 This predicate creates a new external solver state and associates it
 with the eplex instance. Any arithmetic, integrality and bound
 constraints posted for this eplex instance are collected to create the
 external solver state. After this, the solver state can be invoked to 
 solve the eplex problem.<BR>
<BR>
Objective is either min(Expr) or max(Expr) where Expr is a linear
 expression (or quadratic, if supported by the external solver). <BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/lib/eplex/eplex_solve-1.html"><B>EplexInstance:eplex_solve(-Cost)</B></A><A NAME="@default288"></A><DD CLASS="dd-description">
 Explicitly invokes the external solver state. Any new constraints
 posted are taken into account. If the external solver can find an
 optimal solution to the eplex problem, then the predicate succeeds and Cost is
 instantiated to the optimal value. If the problem is infeasible (has no
 solution), then the predicate fails (by default). If the problem is
 unbounded (Cost is not bounded by the constraints), then the predicate
 succeeds without producing any solution values for the variables. </DL>

<A NAME="toc59"></A>
<H3 CLASS="subsection"><A NAME="htoc112">9.2.6</A>&nbsp;&nbsp;Examples</H3>
Here is a simple linear program, handled by the predefined eplex instance 'eplex':
<PRE CLASS="verbatim">
:- lib(eplex).

lp_example(Cost) :-
     eplex: eplex_solver_setup(min(X)),
     eplex: (X+Y $&gt;= 3),
     eplex: (X-Y $= 0),
     eplex: eplex_solve(Cost).
</PRE>
The same example using a user-defined eplex instance:
<PRE CLASS="verbatim">
:- lib(eplex).
:- eplex_instance(my_instance).

lp_example(Cost) :-
     my_instance: eplex_solver_setup(min(X)),
     my_instance: (X+Y $&gt;= 3),
     my_instance: (X-Y $= 0),
     my_instance: eplex_solve(Cost).
</PRE>
Running the program gives the optimal value for Cost:
<PRE CLASS="verbatim">
[eclipse 2]: lp_example(Cost).

Cost = 1.5
</PRE>
Note that if the <TT>eplex</TT> eplex instance is used instead of <TT>my_instance</TT>, then the <TT>eplex_instance/1</TT> declaration is not
necessary.<BR>
<BR>
By declaring one variable as integer, we obtain a Mixed Integer Problem:
<PRE CLASS="verbatim">
:- lib(eplex).
:- eplex_instance(my_instance).

mip_example(Cost) :-
     my_instance: (X+Y $&gt;= 3),
     my_instance: (X-Y $= 0),
     my_instance: integers([X]),
     my_instance: eplex_solver_setup(min(X)),
     my_instance: eplex_solve(Cost).

....
[eclipse 2]: mip_example(Cost).

Cost = 2.0
</PRE>
The cost is now higher because X is constrained to be an integer. Note also
that in this example, we posted the constraints before setting up the 
external solver, whereas in the previous example we set up the solver
first. The solver set up and constraint posting can be done in
any order. If <TT>integers/1</TT> constraints are only posted after problem
setup, the problem will be automatically converted from an LP to a MIP
problem. <BR>
<BR>
This section has introduced the most basic ways to use the eplex library. 
We will discuss more advanced methods of using the eplex instances in
section&nbsp;<A HREF="libman055.html#eplex-instance-advanced">9.3</A>. <BR>
<BR>
<HR>
<A HREF="libman053.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="libman055.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
